Architectural Blueprint & Engine Design

This document provides a deep architectural analysis of Pepvoid Builder, detailing component responsibilities, class hierarchies, data flows, sequence diagrams, and pipeline execution stages.

1. Architectural Principles

Pepvoid Builder follows these core design principles:

  1. Separation of Concerns: Configuration parsing (config_loader), host tools (toolchain), environment execution (chroot_manager), image generation (iso_engine), and rootfs configuration (customizer) are decoupled into specialized modules.

  2. Build Toolchain Isolation: ToolchainManager manages static XBPS tools and per-build toolchain files. The host still needs Linux, the host utilities required by the selected format, network access for uncached downloads, and permissions for chroot or supported proot execution.

  3. Abstract Engine Registry: Architecture engines (VoidEngine, PlatformEngine) register via @ISOEngine.register("name") decorators, allowing new hardware platforms to be added without modifying existing code.

  4. Dual Execution Modes: --mode mock simulates operations without proving an artifact boots; --mode real downloads packages and creates images, using root privileges or supported proot execution as applicable.

  5. Explicit Build Paths: Project-relative configuration, caches, outputs, and work directories are resolved against the detected checkout root; build-specific mutable tools stay inside the build work directory.

2. Complete Execution Sequence Diagram

User / Terminal
      |
      | 1. Execute cli.py [arch] [options]
      v
  cli.py
      |
      | 2. Instantiate BuildOrchestrator
      v
BuildOrchestrator
      |
      | 3. ConfigAssembler.assemble_options()
      v
ConfigAssembler  ===> Reads global_build.json + architectures/ + desktops/ + package_rules.json
      |
      | 4. Return Config object
      v
BuildOrchestrator
      |
      | 5. ToolchainManager.setup() -> Ensure static xbps binaries
      | 6. ChrootManager(chroot_path, toolchain, mode, arch, config)
      | 7. ISOBuilder(arch, config, toolchain)
      v
  ISOBuilder
      |
      | 8. Select engine: VoidEngine or PlatformEngine
      v
Target Engine (VoidEngine / PlatformEngine)
      |
      +---> 1. setup_workdir()
      |
      +---> 2. setup_chroot()
      |
      +---> 3. install_packages() -> ChrootManager.install_packages()
      |
      +---> 4. post_install_configure() -> SystemConfigurator.apply()
      |
      +---> 5. build_bootloaders() -> SYSLINUX / GRUB / U-Boot
      |
      +---> 6. finalize_isofile() / export_tarball() -> mksquashfs / xorriso / tar
      +---> DiskEngine -> partitioned image and optional VM-format conversion
      |
      +---> 7. _generate_manifest_and_checksums() -> checksums, manifest, ephemeral GPG signature
      v
Output Artifacts (.iso / .img / .tar.xz + Manifests)

3. Class Hierarchy & Responsibilities

Module: void_builder.core.config_loader

Config

  • Role: Read-only configuration wrapper providing dot-notation access (cfg.get("system.iso_label")).

ConfigAssembler

  • Role: Recursive dictionary merger.

  • Methods:

    • _deep_merge(base, update): Combines nested dicts and appends list items uniquely.

    • assemble(...): Merges global build settings, architecture config, desktop profile, kernel override, package profiles, service profiles, and dynamic package rules.

    • validate(...): Validates that all requested profile files exist in configs/ and produces a structured audit dictionary.

ConfigLoader

  • Role: Backward-compatible loader helper.

Module: void_builder.core.toolchain

ToolchainManager

  • Role: Downloads and validates static xbps-install.static and xbps-rindex.static binaries.

  • Methods:

    • setup(): Ensures static XBPS and PRoot tools in the project tools cache, then copies the tools into the current build’s workdir/<arch>/<build-id>/build_host/tools directory.

    • _run_xbps_install(...): Executes static xbps-install.static against the target rootfs.

Module: void_builder.core.chroot_manager

ChrootManager

  • Role: Handles pseudo-filesystem mounts (/proc, /sys, /dev, /dev/pts, /dev/shm), package installations, user creation, and chroot command execution.

  • Methods:

    • mount(): Mounts virtual filesystems into target rootfs.

    • umount(): Safely unmounts all virtual filesystems.

    • install_packages(package_plan, repos, reinstall): Installs packages into chroot via the isolated package installer.

    • run_command(command, env, check, input_text): Executes an argument vector or explicit shell command inside the chroot and returns stdout.

    • run_reconfigure(): Runs Void 3-pass xbps-reconfigure -f <pkg> for system packages.

Module: void_builder.core.stage_manager

StageManager

  • Role: Manages base system stage tarballs (void-base-<arch>.tar.xz) for rapid ISO builds.

  • Methods:

    • resolve_tarball(tarball_arg): Resolves a local path, URI (file://), HTTPS URL, or automatic candidate lookup (y/auto). Plain HTTP URLs are rejected.

    • extract_tarball(tarball_path, target_root): Requires real-mode archives to match an explicit SHA-256 or adjacent .sha256 sidecar before extracting with numeric owners and extended attributes. Uses parallel decompressors (pixz, zstd -T0, pigz) when available.

    • create_stage_tarball(source_root, output_tarball, compression): Packages clean rootfs into compressed stage tarball (.tar.xz, .tar.gz, .tar.zst). Automatically applies multi-threaded compressors (zstd -T0 -3, pixz, pigz).

Module: void_builder.core.iso_engine

ISOEngine

  • Role: Abstract base class and engine registry.

  • Registry: Maps architecture names to engine implementation classes.

BaseEngine

  • Role: Abstract base engine providing workspace resolution, manifest generation, and tarball export.

  • Methods:

    • setup_workdir(workdir): Resolves and creates workspace paths.

    • _generate_manifest_and_checksums(output_path): Computes SHA256, SHA512, MD5 hashes, generates manifest.json, and signs the artifact with a temporary per-build GPG key.

    • export_tarball(output_path): Packs rootfs into .tar.xz container tarball.

VoidEngine(BaseEngine)

  • Role: Handles PC ISO 9660 hybrid ISO image building (x86_64, i686, aarch64).

  • Methods:

    • _create_squashfs(): Invokes mksquashfs with configured compression (xz, zstd, gzip), multi-threaded processor allocation (-processors <N>), and fast block sizing.

    • finalize_isofile(output_path): Assembles ISO using xorriso with BIOS El Torito and UEFI GRUB EFI options. Strictly validates xorriso return codes and output media space to prevent corrupted image output.

PlatformEngine(VoidEngine)

  • Role: Handles platform-specific boot assets and root-filesystem staging for registered SBC and device targets.

  • Methods:

    • finalize_isofile(output_path, output_format): Builds ISO output. Disk image creation and raw/VM-format conversion are delegated to DiskEngine by ISOBuilder.

Module: void_builder.core.disk_engine

DiskEngine

  • Role: Creates partitioned disk images and converts them to raw or supported virtual-machine formats.

  • Methods:

    • build_disk_image(target_format): Creates boot and root filesystems, writes the architecture-appropriate partition table and image, optionally converts with qemu-img, and applies configured compression.

Module: void_builder.core.customizer

SystemConfigurator

  • Role: Executes modular, decoupled SystemAction objects inside target rootfs.

  • Action Sequence:

    • RootPasswordAction: Sets root password or locks root account.

    • SSHKeyAction: Injects authorized public SSH keys into /root/.ssh/authorized_keys and /home/<user>/.ssh/authorized_keys with strict permissions.

    • LocaleAction: Applies hostname, timezone, locale, and keymap.

    • UserAction: Creates live user accounts and assigns groups.

    • ServiceAction: Enables Runit services with conflict suppression (e.g. omits dhcpcd if NetworkManager is enabled).

    • HookAction: Executes user-defined shell scripts at lifecycle milestones (pre-install, post-install, pre-iso).

    • DracutAction: Generates initramfs with optimized compression.

    • StructuredCopyAction: Copies overlay file trees from configs/custom_files/.

4. Step-by-Step Pipeline Phases

  1. Phase 1 - Initialization & Presets: BuildOrchestrator parses arguments, applies preset profiles (minimal, developer, gaming, etc.), instantiates ConfigAssembler, and builds master Config object.

  2. Phase 2 - Workdir & TmpFS Staging: Tests write permissions on workdir/<arch>, optionally mounting in-memory tmpfs if --tmpfs is active for maximum I/O throughput.

  3. Phase 3 - Toolchain Preparation: Initializes ToolchainManager and verifies static xbps binaries.

  4. Phase 4 - Chroot Provisioning: Creates airootfs directory and mounts virtual filesystems (/proc, /sys, /dev, /dev/pts, /dev/shm).

  5. Phase 5 - Package Installation: Invokes xbps-install.static with target package plan and repository list (or extracts pre-built base stage tarball via StageManager).

  6. Phase 6 - System Customization & Actions: SystemConfigurator executes SystemAction chain (locale, users, services, SSH keys, root password, hooks, Dracut initramfs).

  7. Phase 7 - 3-Pass Reconfiguration: Runs xbps-reconfigure -a inside chroot.

  8. Phase 8 - Bootloaders & Finalization:

    • For ISO: Generates SYSLINUX/GRUB configs, creates SquashFS (zstd / xz), runs xorriso.

    • For disk output: Create a partitioned image, optionally convert it to raw, QCOW2, VDI, VMDK, VHD, or VHDX, then apply configured compression.

    • For Tarball: Packs rootfs into .tar.xz.

  9. Phase 9 - Checksums, Manifests & Benchmarking: Computes SHA256, SHA512, MD5, generates .manifest.json, safely unmounts filesystems, and prints --benchmark timing breakdown.